Alpha version of VMU2PC software.

See www.tidalwave.net/~maushammer/vmu.html for more details and instructions
and disclaimers. Also read the file lowlevel_dosparallel.c for more details.
This is based on Soeren's version 1.1 software, included in its entirety here.
This alpha version isn't integrated into the 1.1 software yet. It was compiled
with Microsoft visual C++.

-- john maushammer 5/7/2000


-------------------------------------------------------------------------------

SerialToVM software version 1.1

Copyright (C) 2000 by Soeren Gust, sgust@ithh.infoserv.de

******************************************************************
* This text is distributed in the hope that it will be useful,   *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  *
* GNU General Public License for more details.                   *
******************************************************************

This text is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

What is it
----------
SerialToVM lets you connect the Visual Memory to a standard RS-232 serial
port on a PC (or other systems like Amiga etc.). It is possible to send and
receive games and save-files from and to the Visual Memory. It uses the VM
to VM protocol, the same protocol is used when transferring files directly
from one VM to another. Since this protocol is limited to transferring files
it is not possible to do things like reinitialise the VM or copy protected
files.

This package contains just the source to the software currently linux and
AmigaOS only.  Without the hardware it is completely useless. A description of
the hardware can be found at "http://soeren.infoserv.de/vm/".

Send a file to VM
-----------------
To send a file to the VM use sendfile [OPTIONS] FILE. The file FILE will be
sent to the VM as a game file using /dev/ttyS1 as interface. With -d DEVICE you
can change to another interface. With -t 0x33 you can set the type of the
file to data. Use -n NAME to set the filename on the VM. With -v the
program tells what it is currently doing. Using -h gives help.

Receive a file from the VM
--------------------------
To receive a file from the VM first select the file to copy and press A.
Then start receivefile. With -d DEVICE you can select which serial port to
use. Use -n NAME to set the filename on the PC. With -v the program tells
what it is currently doing. Using -h gives help. After starting receivefile
choose "Yes" on the VM to start the copy.

Running on Linux
----------------
The default device on Linux is /dev/ttyS1, override this with the command
line option -d. Make sure that the user running the programs have the
necessary permissions, consult your distribution manual how to do this, or
set the device to 660, make a new group serialvm and add all users to this
group who need access to the SerialToVM.

Running on AmigaOS
------------------
The default device on AmigaOS is serial.device/0. The format of the option
-d is device/unit. I have not tested the programs on devices other than the
normal serial.device of Workbench 3.0 and 2.04. When compiled with dice the
programs can be made resident although this does not make much sense. I
have not tested the programs on Kickstart 1.3, but they should work. They
ran on Kickstart 2.04 (37.175) and Kickstart 3.0 (39.106). Since I don't
have any of the PPC cards the binaries I produced are plain 68000 only.

Possible problems
-----------------
Sometimes if the transfer fails the VM does not respond any more to further
communications. Just physically disconnect the SerialToVM and reconnect it
again.

A possible problem can be one of those new mainboards with big (64 byte) FIFOs
on the serial interfaces. They could cause problems with the buffers I
implemented inside the firmware if they work the same as the 16 byte FIFOs in
the 16550 compatible interfaces with respect to RTS/CTS handshaking. So if you
have problems with one of those boards try disabling the FIFOs. I don't have
access to such mainboards, so I could not test them.

Compiling on Linux
------------------
I have used gcc-2.95.2 on Linux/i386 2.2.14 with libc 6.1 SuSE 6.2 and
gcc-2.7.2 on Linux/m68k/mac 2.2.10 with libc 6.0 Debian 2.0 to successfully
compile sendfile. gcc-2.95.2 on the mac did not work, I think because libc
is too old. To compile it set softlinks from the lowlevel_linux.* files to
lowlevel.*, then just type make.

Compiling on AmigaOS
--------------------
I have used dice-3.16 as found on Aminet together with the AmigaOS includes
version 2.0 I had licensed year ago. To compile it set softlinks from the
lowlevel_amiga.* files to lowlevel.*, then just type dmake.

Porting to other systems
------------------------
All you need to do is write an new lowlevel_xx.c and lowlevel_xx.h. First
define a type used as handle to a serial port, eg. struct IOExtSer * on
Amiga in lowlevel_xx.h. This should be a pointer or int, it is initialised
to 0.  Then write functions to open and close the serial port called
openserial and closeserial. Openserial gets the name of the serial port as
a char *. Initialise the port to 19200,8,n,1 using RTS/CTS and DTR
handshaking. Create and initialise any additional things needed later, like
opening timer.device for timeouts used later or whatever you need. Return 0
on error and 1 on success. Closeserial should delete all resources
allocated in openserial. All communication with the serial port happens in
single bytes in readserial and writeserial. Both have a timeout value
giving a maximum time to be successful. Return -1 if something went wrong,
-2 if a timeout occurred and the byte casted to an int on success.

For some of the rest of the programs you need POSIX like functions, I
have used fstat() to get the size and creation time of the file, getopt() to
parse parameters and utime() to set the timestamp of files. For the Amiga I
have included a free version of getopt() and wrote my own version of
utime().

The lowlevel_linux.c should work on most unixoid systems without major changes,
I got it to work on an ancient netbsd/m68k macintosh by removing O_SYNC, but
have not done any real tests on the binary, last boot of that system had
been more than 2 years ago and I was just curious.
